Crate rhai

Rhai - embedded scripting for Rust

Rhai is a tiny, simple and very fast embedded scripting language for Rust that gives you a safe and easy way to add scripting to your applications. It provides a familiar syntax based on JS and Rust and a simple Rust interface. Here is a quick example.

First, the contents of my_script.rhai:

// Brute force factorial function
fn factorial(x) {
    if x == 1 { return 1; }
    x * factorial(x - 1)
}

// Calling an external function 'compute'
compute(factorial(10))

And the Rust part:

use rhai::{Engine, EvalAltResult, RegisterFn};

fn main() -> Result<(), Box<EvalAltResult>>
{
    // Define external function
    fn compute_something(x: i64) -> bool {
        (x % 40) == 0
    }

    // Create scripting engine
    let mut engine = Engine::new();

    // Register external function as 'compute'
    engine.register_fn("compute", compute_something);

    assert_eq!(
        // Evaluate the script, expects a 'bool' return
        engine.eval_file::<bool>("my_script.rhai".into())?,
        true
    );

    Ok(())
}

Optional features

Feature	Description
unchecked	Exclude arithmetic checking (such as overflows and division by zero). Beware that a bad script may panic the entire system!
no_function	Disable script-defined functions if not needed.
no_index	Disable arrays and indexing features if not needed.
no_object	Disable support for custom types and objects.
no_float	Disable floating-point numbers and math if not needed.
no_optimize	Disable the script optimizer.
only_i32	Set the system integer type to i32 and disable all other integer types. INT is set to i32.
only_i64	Set the system integer type to i64 and disable all other integer types. INT is set to i64.
no_std	Build for no-std. Notice that additional dependencies will be pulled in to replace std features.
sync	Restrict all values types to those that are Send + Sync. Under this feature, Engine, Scope and AST are all Send + Sync.

Check out the README on GitHub for details on the Rhai language!

Modules

packages

This module contains all built-in packages available to Rhai, plus facilities to define custom packages.

Macros

def_package

This macro makes it easy to define a package and register functions into it.

Structs

AST	Compiled AST (abstract syntax tree) of a Rhai script.
Dynamic	A dynamic type containing any value.
Engine	Rhai main scripting engine.
ParseError	Error when parsing a script.
Position	A location (line number + character position) in the input script.
Scope	A type containing information about the current scope. Useful for keeping state between Engine evaluation runs.

Enums

EvalAltResult	Evaluation result.
OptimizationLevel	Level of optimization performed.
ParseErrorType	Type of error encountered when parsing a script.

Traits

Func	A trait to create a Rust anonymous function from a script.
FuncArgs	Trait that represents arguments to a function call. Any data type that can be converted into a Vec<Dynamic> can be used as arguments to a function call.
RegisterDynamicFn	A trait to register custom functions that return Dynamic values with the Engine.
RegisterFn	A trait to register custom functions with the Engine.
RegisterResultFn	A trait to register fallible custom functions returning Result<_, Box<EvalAltResult>> with the Engine.

Functions

calc_fn_hash

Calculate a u64 hash key from a function name and parameter types.

Type Definitions

Array	An dynamic array of Dynamic values.
FLOAT	The system floating-point type.
INT	The system integer type.
Map	An dynamic hash map of Dynamic values with String keys.